Skip to content

feat(protocol): publish protocol v1 schemas, golden vectors, and conformance runner - #6

Draft
CompleteDotTech wants to merge 4 commits into
mainfrom
agent/issue-11-publish-psyche-protocol-v1-schemas-golden
Draft

feat(protocol): publish protocol v1 schemas, golden vectors, and conformance runner#6
CompleteDotTech wants to merge 4 commits into
mainfrom
agent/issue-11-publish-psyche-protocol-v1-schemas-golden

Conversation

@CompleteDotTech

@CompleteDotTech CompleteDotTech commented Aug 30, 2026

Copy link
Copy Markdown
Owner

Summary

Publishes the consumer-ready Psyche protocol v1 release surface required by OpenCoven#11, on top of the G2 foundation:

  • protocol/v1/ — generated, checksummed artifact set. Self-contained JSON Schema (draft 2020-12) for all sixteen registry kinds (psyche.identity_snapshot.v1 … psyche.error.v1), the Coven boundary types (psyche.execution_request.v1 launch/input, result bundle), and the store-owned transition; a generated TypeScript surface; byte-exact canonical JSON golden vectors with pinned SHA-256 digests; a machine-readable inventory with stability classes (stable-v1 / experimental / internal / deprecated); and a sha256sum-format MANIFEST.sha256 for downstream pinning.
  • Golden vectors cover every fixture class Publish Psyche protocol v1 schemas, golden vectors, and conformance runner OpenCoven/psyche#11 requires: positive, structured denial, stale-correlation (ack outside window, expired request window, evidence session mismatch), unknown-version (psyche.intent.v2), crash/restart (append-only revision chain whose revision 2 binds previous_revision_digest to revision 1's canonical bytes, plus a broken-chain profile-rejection), and downgrade (fail closed on an unsupported major).
  • packages/psyche-protocol/ — standalone conformance runner (psyche-conformance). Zero dependencies, no network, no credentials, bounded machine-readable output. Implements the consumer-v1 profile: negotiation, session/execution correlation, snapshot/attempt binding, adoption proof, ambiguity/fencing shape, cursor/restart, terminal-authority shape, the full cancellation evidence matrix (ported from ExecutionBinding::validate_cancellation), result/artifact binding (ported from ResultBundle::validate), append-only revision chains and frozen fields (ported from validate_revision_chain), structured-denial/quarantine classification (RejectionReason vocabulary), and the canonical JSON domain.
  • scripts/protocol/ — single source of truth + deterministic generator. node scripts/protocol/generate.mjs rewrites the artifact tree byte-identically; a new CI job re-runs it and fails on any uncommitted drift (schemas, fixtures, generated TypeScript).
  • crates/psyche-core/tests/protocol_golden.rs cross-checks every registry golden vector through the real decoder and byte-compares canonical_bytes against the published files — schema↔decoder drift is caught in both directions.
  • docs/PROTOCOL.md — the compatibility policy: semantic versioning of the artifact set, compatibility windows, unknown-field/enum/kind/major fail-closed behavior, migration/downgrade/rollback, deprecation, the conformance profile mapping, and decision records with alternatives.

Canonicalization is RFC 8785. The JavaScript canonicalizer is pinned to byte parity against Rust-produced digests this repo's own CI already verifies: sha256:75d651c5… / sha256:c8c3d0ca… (execution request goldens) and both decoder-recomputed effect_digest values. The execution-request golden vectors are byte copies of the Rust fixtures, so their file digests are the pinned request digests.

Issue

Refs OpenCoven#11

Test plan

  • node scripts/protocol/generate.mjs --check — artifact drift clean (56 files)
  • npm --prefix packages/psyche-protocol test — 30/30 node:test unit tests (canonicalizer byte-parity vs Rust goldens, schema validator, full cancellation/revision/binding/negotiation matrix, CLI end-to-end + tamper detection)
  • psyche-conformance run --root protocol/v1 — 33/33 vectors pass, exit 0; tampered copies exit 2
  • psyche-conformance verify --root protocol/v1 — 55 files + 33 vectors verified, exit 0
  • cargo fmt --all -- --check — clean (pinned 1.88.0 toolchain)
  • cargo test -p psyche-core --test protocol_golden and the full CI rust matrix — compile proof deferred to CI (no local linker)
  • New protocol CI job green (generate/drift, runner tests, conformance, manifest verification)

Vehicle note: opened in the fork CompleteDotTech/psyche as the CI vehicle — this token cannot write to OpenCoven/psyche. Re-target upstream once write access is restored. Refs OpenCoven#11.

@CompleteDotTech
feat(protocol): publish protocol v1 schemas, golden vectors, and runner
2f05596 
Publish the consumer-ready Psyche protocol v1 release surface required
by issue OpenCoven#11 on top of the G2 foundation:

- protocol/v1/: generated artifact set - self-contained JSON Schema
  (draft 2020-12) for all sixteen registry kinds plus the Coven
  boundary types and the store-owned transition, a generated
  TypeScript surface, byte-exact canonical golden vectors
  (positive, denial, stale-correlation, unknown-version,
  crash/restart, downgrade) with pinned SHA-256 digests, a
  machine-readable inventory with stability classes, and a
  sha256sum manifest for downstream pinning.
- packages/psyche-protocol/: standalone, dependency-free conformance
  runner (psyche-conformance) implementing the consumer-v1 profile -
  negotiation, correlation, snapshot/attempt binding, adoption proof,
  fencing shape, cursor/restart, terminal authority shape, the full
  cancellation evidence matrix, result/artifact binding, append-only
  revision chains, structured-denial classification, and the
  canonical JSON domain. Emits bounded machine-readable results; no
  network, no credentials.
- scripts/protocol/: single source of truth (definitions.mjs,
  vectors.mjs) and a deterministic generator; CI re-runs generation
  and fails on uncommitted drift.
- crates/psyche-core/tests/protocol_golden.rs: cross-checks every
  golden vector through the real decoder and byte-compares
  canonical_bytes against the published artifacts.
- docs/PROTOCOL.md: inventory, classification, canonical bytes,
  semantic versioning, compatibility windows, unknown-field/enum
  fail-closed behavior, migration/downgrade/rollback, conformance
  profile, and decision records.

Canonicalization is RFC 8785; the JavaScript implementation is pinned
to byte parity against the Rust-pinned request digests
(sha256:75d651c5... launch, sha256:c8c3d0ca... input) and the
decoder-recomputed effect digests.

Refs OpenCoven#11

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech CompleteDotTech self-assigned this Aug 30, 2026
@CompleteDotTech
fix(protocol): gate the transition vector off the registry decoder
d33fd79 
The store-owned transition carries no schema_version of its own, so
decode_document must deny it; the positive-vector cross-check ran the
decode before reaching the None branch. Restructure the loop so
store-owned vectors assert denial and registry vectors decode and
re-canonicalize, matching docs/PROTOCOL.md section 2.

Refs OpenCoven#11

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
fix(protocol): separate not-persistable vectors from non-document vec…
bba78cb 
…tors

psyche.error.v1 decodes exhaustively and only then refuses
persistence, so the error-envelope golden vector belongs in the
decode-and-recanonicalize path without an id-prefix assertion, while
psyche.transition alone is a non-document. Encode the three cases as
an explicit IdExpectation so each is asserted on its own terms.

Refs OpenCoven#11

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech
chore(ci): re-pin the reviewed workflow hash for the protocol job
66e86f3 
Adding the protocol job to .github/workflows/ci.yml (issue OpenCoven#11 drift
gate) changes the reviewed workflow content, so the evidence checker's
hash pin must be updated in the same reviewed change. Root triggers,
global env, the rust matrix, required job shapes, and every pinned G2
command are unchanged and still verified structurally.

Refs OpenCoven#11

Signed-off-by: Timothy Wayne Gregg <5861166+CompleteDotTech@users.noreply.github.com>
@CompleteDotTech

CompleteDotTech commented Aug 30, 2026

Copy link
Copy Markdown
Owner Author

CI status on this fork vehicle — verdict and one unrelated failure

Green (every run): Protocol artifacts (Node 22) (generate/drift gate, runner unit tests, conformance over 33 vectors, manifest verification), npm distribution ×2, Secret guard, Dependency audit, and on the rust legs: Format, Clippy, Tests, G2 state machine, G2 reusable conformance, G2 migrations, G2 crash recovery, G2 fault-injection clippy, G2 evidence checker unit tests.

Fix cycles applied to this PR (3 of 4):

  1. protocol_golden.rs ran the registry decoder over the store-owned transition vector; restructured so store-owned vectors assert decoder denial and registry vectors decode + re-canonicalize.
  2. Separated IdExpectation::NotPersistable (psyche.error.v1 decodes but never persists) from IdExpectation::NotADocument (psyche.transition is not a registry document).
  3. Re-pinned REVIEWED_WORKFLOW_SHA256 in scripts/check-g2-evidence.py for the reviewed addition of the protocol job (the checker hashes the complete CI workflow; no G2 command, trigger, env, or job shape changed — all still verified structurally).

Two failures that are NOT caused by this PR:

  1. G2 evidence relationships — fails with G2 evidence check failed: GitHub Actions repository provenance is invalid on all three OS legs. scripts/check-g2-evidence.py::verify_actions_source_relationship requires the CI event's repository.full_name (and PR head repo) to be exactly OpenCoven/psyche — a deliberate upstream-provenance gate. On the fork CompleteDotTech/psyche this step cannot pass by construction, independent of the change contents. It will pass when this PR is re-targeted upstream; everything it depends on (hash pin, structural checks, evidence relationships logic) is verified green around it, and the unit-level mutation suite (G2 evidence checker unit tests) passes.

  2. One transient windows failure of concurrent_first_open_applies_migration_once (crates/psyche-store/tests/migrations.rs:556) — a pre-existing store concurrency test this PR does not touch (no psyche-store source change in the diff). It passed on job re-run; recorded here as a flake observation.

Per the CI contract this PR therefore stays draft: it is green except a step that is structurally impossible on the fork vehicle. Re-target upstream (restore write access to OpenCoven/psyche) and the full matrix should be green as-is — no content change expected.

Refs OpenCoven#11

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@CompleteDotTech CompleteDotTech

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@CompleteDotTech